MacWorld 1998 March/Macworld (1998-03) (Disk 1).dmg/Shareware World/Utilities/Text Processing/Alpha/Help/ElecCompletions Help

Text File | 1997-12-01 | 16.7 KB | 448 lines | [TEXT/ALFA]

##
 # ###################################################################
 #  Vince's Additions - an extension package for Alpha
 #
 #  FILE: "ElecCompletions Help"
 #                                    created: 1/8/97 {2:24:21 pm}
 #                                last update: 1/12/97 {5:46:17 pm}
 #  Author: Vince Darley
 #  E-mail: <[e-mail]>
 #    mail: Division of Engineering and Applied Sciences, Harvard University
 #          Oxford Street, Cambridge MA 02138, USA
 #     www: <http://www.fas.harvard.edu/~darley/>
 #
 # Copyright (c) 1997  Vince Darley
 #
 # ###################################################################
 ##

If you want basic help/tutorial information, do the following: when
you're in a mode for which you want a tutorial on electric completions,
select 'Completions Tutorial' from the 'Current mode' menu.  Follow
the instructions there.

Recent changes:

The code has been split into separate packages.  The better templates code
is now optional --- it is slow on slow machines so some people prefer not
to use it, but still like all the electric completions etc.  The problem
is that the standard template code lacks some of the more advanced features
of my version.

You can modify the following preferences using the
'Config->Global->Flags->Electrics' menu item:

    • useElectricMenu --- use electric template menu
    • showElectricsInMenu --- show electric completions in menu
    • showElectricKeysInMenu --- show electric key bindings in menu
    • modeSpecificElecTab --- use mode-specific electric tab
    • electricTab --- use electric tab
    • templateStopColor --- colour of template stops
    • listPickIfMultExpds --- similarly for expansions
    • ElectricFillers --- The format of the template stops:
          0 = just use bullets
          1 = use bullets but signal the name in the status window
          2 = insert names into the window with the bullets
          3 = insert names and highlight into the window with the bullets
    • maxTemplateNesting--- level of nesting we allow before clearing

The electric menu contains a 'Templates' sub-menu, which contains global
templates stored in the variable 'univ::MenuTemplates', and mode-specific
templates stored in variables ${mode}Templates.  The format of these
variables is a list of names, which correspond to procedures when prepended
with 'file::'.  You can add new items by using the menu item.

          Templates

Many of the routines in Vince's Additions allow you to insert templates for
'for' loops, '\begin...\end environments', file headers, function comments,
and even entire documents.  This section details the features of Vince's
Additions which allow you to do that.  Here's an example of a 'for' template
in C++ mode (created just by typing 'for<cmd-Tab>'):

    for (•<init>;•<test>;•<increment>){
        •<loop body>
    }
    •

Once a template has been inserted, it will often contain a number of
'place-markers' or 'template-stops' at each of which you will most likely
wish to enter some text/code.  You can jump backwards and forwards amongst
these stops using a set of key bindings.  You have a choice between two
basic sets (you select using the 'Electric Bindings' dialog):

    Operation               Standard Bindings         Alternative Set

    "Next Stop Or Tab"       Tab                       ctrl-j
    "Complete"               cmd-Tab                   cmd-Tab
    "Expand"                 cmd-Space                 Tab
    "Prev Stop"              shift-Tab                 shift-ctrl-j
    "Real Tab"               opt-Tab                   opt-Tab
    "nth Stop"               ctrl-Tab                  ctrl-opt-j
    "Clear All Stops"        shift-ctrl-Tab            shift-ctrl-opt-j

Furthermore you can redefine any of these bindings using that same
dialog.

You have a choice between four different formats for the visual appearance
of the template-stops.  They are usually signified by a bullet '•', but
more elaborate methods are supported.  These templates may be nested
without any extra effort on your part.  Most of this code is contained in
the file "univTemplates.tcl", although all the bindings and initialisation
are in "univBindings.tcl".

Look at the new 'electric' menu for a list of these bindings, together
with some other functions.

================================================================================

          Completions

I've now written a unified collection of procedures to address command
completion, code indentation, electric-code generation, word completion and
related facilities (incorporating my old TeX-reference completion for
example).

Here's a typical example from TeX mode, I type:

    for an explanation of this phenomenon,
    please refer to Fig<cmd-Tab>

The <cmd-Tab> signifies that Vince's Additions should try to complete the
currently typed text.  In this case the completion is:

    for an explanation of this phenomenon,
    please refer to Figure~\ref{fig-

If I hit <cmd-Tab> again, Vince's Additions tries to search for TeX
'\labels' which begin with 'fig-' to insert the first such label
it finds into the text:

    for an explanation of this phenomenon,
    please refer to Figure~\ref{fig-heat-vs-time}

If this is the wrong one, I can keep hitting <cmd-Tab> until I reach the
correct completion:

    for an explanation of this phenomenon,
    please refer to Figure~\ref{fig-explanation}

Here's an example from C/C++ modes. I type 'for<cmd-Tab>' and get:

    for (;•;•){
        •
    }

This works at any current level of indentation, and the bullet marks '•'
are placemarkers.  You can just press 'Tab' (without 'cmd') to jump from
one to the next.

These facilities are activated as follows:

•    Tab --- plain - either 'indent' or 'next template mark'
            cmd   - complete the current text.
            opt   - insert a real tab.

So, pressing Tab by default will _not_ necessarily insert a tab, rather it
will indent the current line of code to the correct indentation level to
match the code around it.

            Types of completion


Command-Tab has a number of different meanings, which will be explained
below.  Completions are listed in order of precedence.

              User completion:

all entries defined in the array 'userCompletions' are checked and inserted
if appropriate.  This is useful to make 'vmd' turn into 'Vince Darley', or
'www' into my home-page url, or ...

User completions are active in all modes, and take precedence over all
other completion types.

              Context sensitive completion:

Context sensitive completions are mode dependent.  In some modes you
can tell relatively easily from the context whether a particular
'word' is a variable or procedure name or...  If different completion
procedures are useful for different types of word, then they are
checked next.  For instance, in Tcl mode, a word beginning with '$',
or preceded by 'set' or 'global' is a variable name.  It should
therefore be completed preferentially as a variable, rather than
being expanded as a command.  E.g. $str should normally not be
expanded to '$string ...' since it's clearly not the command 'string'
that the user is trying to type.

              Command completion:

For instance: type 'str<cmd-tab>' and it is completed to 'string' (in Tcl
mode).  If there are multiple possibilities then the longest unique prefix
is inserted.

The available completions are mode dependent, and stored as a large string
in the variable ${mode}cmds.  They must be stored alphabetically, be
separated by whitespace, and have a single space at the beginning and end
of the large string.

Here is the default value for Tcl mode:

    set Tclcmds { append array catch close concat continue elseif error
    for foreach format lindex lsearch lsort regexp regsub
    rename return string switch while }

              Ensemble completion:

type 'string co<cmd-Tab' and this is both completed to 'string compare' and
an electric template is inserted for the arguments of this two part
command.  Useful for any case in which the word before last is the command,
and the word just before is part of a refinement of that command, in any
situation for which a number of further arguments will be filled in.

              Electric code template generation:

type 'for<cmd-tab>' and a complete template for code is generated (example
for C mode):

    for (;•;•){
        •
    }

You can move from one template mark '•' to the next with, plain 'Tab' -
I automatically sense whether a template insertion is in progress or
not and interpret tab accordingly.

These are again mode dependent. Each is stored individually as an element
of the array ${mode}electrics, so, for instance the above electric code is
generated by:

    set Celectrics(for) " (••;••;••)\{\n\t••\n\}\n••"

Note how the bullets are double in the definition.  You can actually place
an explanatory bit of text between pairs of bullets.  This is then used as
a hint to the user:

    set Celectrics(for) " (•start•;•test•;•increment•)\{\n\t•body•\n\}\n••"

              Class name completion:

In C++ mode, when entering a class definition, the class name occurs
multiple times.  To save entering all of these, this completion will
fill them all in for you.  It works like this: type 'class<cmd-tab>'

    class •<object name> : public •<parent> {
      public:
        •<object name>(•<args>);
        ~•<object name>(void);

    };
    •

Now type the class name, say 'toaster', followed by <cmd-tab>.  This
will result in:

    class toaster : public •<parent> {
      public:
        toaster(•<args>);
        ~toaster(void);

    };
    •

i.e. each occurrence of the electric stop 'object name' has been
filled in correctly.  This feature may be easily extended to more
complex examples.

              TeX reference completion:

type '\ref<cmd-Tab>' and the command is automatically completed with the
name of a nearby \label{}.  Repeated <cmd-Tab> keypresses will cycle
through all \label's.  Further, these commands chain together, so typing
'\eqr<cmd-Tab>' will complete the \eqref and continue to fill in a nearby
label!

These were explained above.  Note that the reference completions can be
instigated by command completion on, 'Fig' 'Chap' 'Eq.'  'Sec', ...  which
insert the standard label prefix 'fig:' 'chap:' 'eq:' 'sec:' as
appropriate.  If you complete with no prefix, then any label will match; if
you have a prefix then only those which match will be suggested.

              TeX citation completion.

Type '\cite{Darley19<cmd-Tab>' and the command is completed with a matching
citation entry from one of your '.bib' database files.  If there are
multiple possibilities, then you are prompted with a list from which to
choose.  (Note: if you find the selection box a bit narrow, it is possible
to edit Alpha using ResEdit to increase its size).  Depending upon the
value of a TeX flag, the list can include the titles of each choice,
making it more obvious to you which is correct.

              TeX environment completion:

\begin{} \end{} pairs with synchronisation of the parameter, and template
generation of the body.

You can complete '\begin<cmd-Tab>' followed by 'equ<cmd-Tab>' to the
following:

    \begin{equation}
        •
        \label{eq:•}
    \end{equation}
    •

You have a choice between the double-completion, as above, or just typing
'\begin{equation}<cmd-Tab>' which will do the job in one go.

Similar things work for 'itemize' 'enumerate' etc.  Of particular use
are the completions for 'figure' environments, from which you can enter
ordinary figures, floating figures, and a large number of sub-figure
configurations (2 figures side-by-side, a block of 4,...).  For instance,
a handful of key-presses will give you this:

    \begin{figure}
        \centering
        \subfigure[•“subfig caption”]{\label{fig:•}%
            \includegraphics[width=\figstwo]{•“graphics file”}}\goodgaptwo
        \subfigure[•“subfig caption”]{\label{fig:•}%
            \includegraphics[width=\figstwo]{•“graphics file”}}\\
        \subfigure[•“subfig caption”]{\label{fig:•}%
            \includegraphics[width=\figstwo]{•“graphics file”}}\goodgaptwo
        \subfigure[•“subfig caption”]{\label{fig:•}%
            \includegraphics[width=\figstwo]{•“graphics file”}}%
        \caption•“[short caption for t.o.f.]”{•“caption”}
        \label{fig:•}
    \end{figure}
    •

For these to work, you must use the correct LaTeX packages (graphics,
floatingfigure or subfigure as appropriate, although the code will
automatically insert the correct 'usepackage' specifications for you if
desired), and you may need the following definitions in your LaTeX
preamble:

    \newlength{\goodspace}
    \newlength{\goodspacethree}
    \newlength{\goodspacefour}
    \newlength{\figstwo}
    \newlength{\figsthree}
    \newlength{\figsfour}

    \setlength{\goodspace}{\subfigtopskip+\subfigbottomskip}
    \setlength{\goodspacethree}{\goodspace}
    \setlength{\goodspacefour}{\goodspace*\real{0.6}}

    \newcommand{\goodgap}{\hspace{\goodspace}}
    \newcommand{\goodgaptwo}{\goodgap}
    \newcommand{\goodgapthree}{\hspace{\goodspacethree}}
    \newcommand{\goodgapfour}{\hspace{\goodspacefour}}

    \setlength{\figstwo}{(\linewidth-\goodspace)/2-1pt}
    \setlength{\figsthree}{(\linewidth-\goodspace *2)/3-1pt}
    \setlength{\figsfour}{(\linewidth-\goodspace *\real{1.8})/4-1pt}

These allow good alignment and spacing for most subfigure combinations
without the need for manual intervention.

Some environments can contain an arbitrary number of items.  In this case,
hitting 'shift-option-i' will add an item.  Here we turn this:

    \begin{description}
        \item[First one] here's the description

        \item[•“name”] •“description”

    \end{description}
    •

into:

    \begin{description}
        \item[First one] here's the description
        \item[•] •

        \item[•“name”] •“description”

    \end{description}
    •

Similar entries work correctly for itemised, enumerated, aligned,...
environments.

              File-name completion:

Useful for Shel mode, this allows you to type a partial directory or
filename and hit cmd-Tab to have it extended as much as possible.

              Tcl Variable Completion:

Tcl variables are often referenced with '$var' or just 'var' or '${var}'.
You can complete between any of these types.  A local search for a match is
done and the closest match inserted.  Again you can cycle through other
matches with <cmd-Tab>

              Word Completion:

if none of the above succeeded then the current word is completed to copy
nearby words (variable names) in the file.  Again, repeated presses will
cycle through other possibilities.

In any form of text in any mode, if no mode-specific completion matches,
then any local word can match, complete and be cycled through as usual.

            Template insertion

You'll notice in a lot of the above examples that bullets '•' are inserted
into the text.  In fact the user has a choice of four different levels of
interaction with the template insertion procedures.  You can change this
using the universal preferences dialog (in the config menu).  You can move
from one insertion point to the next using the 'tab' key; move backwards
with 'shift-tab' and jump to any insertion point with 'ctrl-tab'.  If you
don't like these key bindings, an alternative set is available by a change
in the universal preferences.  You can also choose the colour of the
inserted bullets/prompts.

            The Electric Menu

By default all items in the ${mode}electrics array are inserted into a new
menu.  This allows you to insert them, and get a feel for a small number
of the completions which exist.  Also at the bottom of the menu are items
for each of the standard key bindings these routines use, to help you to
remember them.

            Completion feedback

Help me to help you!

Completions for some common items just don't currently exist.  So if you
try to complete something and it doesn't work, why not write a completion
for it?  Once you have assembled a few, mail them to me (preferably
binhex'd, since bullets '•' don't travel well by ASCII mail).  I'd
particularly like completions for other modes.

            Speed

Alpha has some limitations which means some aspects of Vince's Additions
are a little bit slow (on low-end machines, at least).

Two things you can do to alleviate this: first, in modes for which Tab (or
ctrl-j under the alternative bindings) ALWAYS means to go the next template
stop and never means to indent the current line, define a new mode variable
'tabNeverIndents' by adding the following line to your "prefs.tcl":

    newPref f tabNeverIndents 1 MODE

where 'MODE' is 'TeX', 'Java', 'HTML' or whatever.  You'll need to add one
such line for each relevant mode.

The second thing you can do is to mail Pete Keleher to ask for new features
and fixes which will improve this problem.  What is needed is:
  (i) GetTMarkPos ?-w win? name  --- find pos of Tmark 'name' in window
  (ii) GetTMarks ?-w win?        --- list Tmarks in given window only
  (iii) curWin ?-f?              --- return uppermost window name (full path)
  (iv) a bug fix so 'GetTMarks' doesn't think non-file windows are in
  Alpha's HOME directory.

================================================================================